Freelog 41/Freelog041.iso/Palm/Morse Pilot/README.txt

Text File | 2002-12-15 | 19KB | 438 lines

README.txt for Morse Pilot 3.1


APPLICATION:

Morse Pilot 3.1
2002 12 15


AUTHOR:

Dafydd Gibbon, DJ0MZ, [e-mail]


WHAT's NEW:

See the RELEASE NOTES below.


DESCRIPTION:

Text to morse decoder and encoder for PalmOS handheld devices, with tutoring
functions and additional hard button and switchable earcon SUI (Sound User
Interface) interaction for blind users. I would be very interested in getting
feedback, especially from blind users.

Morse Pilot is designed for emulating and practising a wide range of ham radio
sending and receiving scenarios, but is also suitable for learning morse code
in connection with other services. For example, the alphabetic and learn/test
output functions can be used for learning navaid codes in aviation contexts,
and custom learn/test materials for this purpose can be designed using the
Palm MemoPad.

No manual is provided, except for this README file, even though Morse Pilot is
a rather complex programme in many ways. Experience shows that the typical
Morse Pilot user is experimentally minded, and would not read a manual or
even a README anyway - you are an exception if you have got this far, so
congratulations, and read on!

The builtin Morse Pilot lesson presentation strategy takes the alphabet first,
then digits, then punctuation. Alphabet presentation is based on the length
of codes (code length also roughly approximates to frequency of occurrence
in English). After each lesson which introduces new codes there is a lesson
which revises all codes introduced so far.
Custom lesson sets with up to 26 custom lessons can be imported from MemoPad
(format: filename line, then up to 26 lines containing characters, digits,
punctuation (no spaces, no line numbers), one for each lesson.
A test function is provided, with a histogram to monitor progress.

Morse Pilot is a PocketC application.


LICENCE:

Morse Pilot is Freeware. You may freely distribute Morse Pilot, but if you beam
it, you must also distribute the latest versions of the libraries and text
files using an appropriate utility like Beam Box, or the app will not work.
See below.

The author gives no warranties of any kind, express or implied.

If you find this app useful please donate time or money or both to your local
blind community, encourage the development of sound and tactile interfaces for
blind users, and support blind radio hams.


INSTALLATION AND UPDATES:

Install the files as follows, using your favourite installation method.

1. Install morse_pilot.prc (app).
2. Install PToolboxLib750.prc (graphics and audio library).
3. Check the launcher menu on your handheld to see if MathLib.prc (math
   library) is already installed. If not, install it.
4. The DXCC.pdb and MorseQSO.pdb files contain information and practice texts,
   and are not necessary for most purposes. To save space, only install them
   if you need them.

If PToolboxLib or MathLib are not installed, you will be warned to install
them when you launch Morse Pilot on the handheld. If the version of PToolboxLib
is lower than the version in the distribution, you will also be warned.

If you have a PalmOS version number lower than 3.5 you may have a problem with
incompatible graphics. If so, contact me.

If you install from one handheld to another by beaming, you must also beam
the libraries and the DXCC and MorseQSO files from your distribution, or the
app will not work on the other handheld. This is not possible with the
standard beaming function, so you should use an appropriate beaming utility
such as Beam Box. Beam Box is discontinued shareware but you can find download
sites by searching for "Beam Box.prc" with Google (note: not "BeamBox.prc").

If you do not have any of the libraries, the maximal installation size is 312k
static RAM memory, and about another 100k is needed for dynamic memory use,
totalling about 400k. The total is about 50k less if you do not install the
text files.

The dynamic memory requirement is mainly due to the use of graphics buffers
for some of the menu panels and widgets.


HANDLING:

The best way to find out how to use Morse Pilot is to tap your way through the
menus and try everything out. If you get stuck, tap the launcher button,
re-launch Morse Pilot and tap the Reset button in the Main Panel, then Yes
in the dialogue box.

One feature is a little unusual: In the Calibrate and Set Audio panels, when a
button is tapped in order to input new values, a dialogue box appears with the
current value. After entering the new value (or to re-enter the old value),
enter a newline character (stroke top right to bottom left on either the
alphabet or the digit side of the Graffiti pad). Or, if the time-out feature
is set, just wait a few seconds. Some external keyboards work with Morse Pilot;
in this case, just type the Return key as expected.

Note that Morse Pilot works with both Graffiti external keyboard input.


TYPICAL USES:

- Morse input practice via long and short taps on the screen
- Training in morse code reading with output from single graffiti, graffiti
  line input, memopad, clipboard, canned text buttons
- Graded lessons in morse reading (customised input from user-produced memos;
  not included in the distribution), with custom lesson option
- Advanced morse output practice with random samples of characters, digits,
  Q signals, other abbreviations, QSO texts (the texts are included in the
  documentation, for comparison with transcripts)
- Tutoring with variable Farnsworth timing (faster characters, longer spaces
  between them)
- Elbug sending practice


HINTS ON STARTING TO LEARN MORSE WITH MORSE PILOT:

There is absolutely no substitute for an expert tutor and lots of practice,
especially listening to real-life morse code (cw - continuous wave)
applications. And also no substitute for using a high quality morse key,
which your tutor will advise you about. Morse Pilot is intended to help you
with intensive practice at convenient times and places, without bulky
equipment.

Hints:
1) Learn to listen and decode before you start learning to send code.
2) Start working through the listening lessons in LEARN mode to familiarise
   yourself with code-character decoding
3) Switch to TEST mode when you think you are sufficiently familiar with the
   material.
4) Enjoy your mistakes - they will ensure that you know exactly what to
   practise!
5) Remember that there are several possible reasons for making mistakes:
   Listening:
    a) Not being able to hear the code properly (too quiet; noise)
    b) Not knowing the particular code combination
    c) Confusing the code combination by a "slip of the ear"
   Writing:
    d) Decoding correctly but not knowing the graffiti stroke
    e) Decoding correctly but writing the wrong character
        (a "slip of the pen")
    f) Writing unclearly so it is wrongly detected - handheld graffiti
        introduce a source of error which can be frustrating if you
        do not write clearly
   Any given error may of course be due to any or all of these factors.
   You will probably find after a little practice that you are making more
   graffiti errors than decoding errors; this means that it is very hard to
   reach a progress score of 100, especially in the lessons with large
   character sets, so it is more realistic to aim for a score of 80 or 90.
   Actually you are also training graffiti writing at the same time as code
   listening, and when you move between handwriting or keyboard this will also
   take a little getting used to. This is normal. In order to minimise graffiti
   writing errors, try writing graffiti characters larger, more exaggerated and
   more slowly than normal.
6) When first working through the lessons, aim for 50% for each lesson first
   time through, then 60% etc. You will need to go through the lessons several
   times. Finally, aim for around 95% or better.
7) Start with the speed you are aiming for (e.g. 6 wpm, 12 wpm etc.), but
   at some point go 50% higher and make sure that you can read a little faster
   than required.
8) When you have finished the lessons, move to the other random code generators,
   first the Q groups, then the 5 character groups, then the QSO texts. Or
   create your own texts as memos, and generate these.
9) It is also a good idea to practise with different sound volume levels in
   order to get used to realistically faint signals.
10) Most important of all - listen to real CW signals on the air ...


UPDATES:

1) Note that all files should currently be in RAM, not on a memory card; it
should be possible to keep all the files into Flash ROM if required (except
the automatically generated Preferences file).

2) If there is a display problem (e.g. low contrast) please let me know, with
details of the device and PalmOS version you are using. First try the
black/white version which is now distributed (as from Version 2.4.3). This
problem seems to occur with older devices which have PalmOS 3.1 or 3.3.

2) After installing an update, the Preferences database generally has a
different format, and may produce unpredictable parameter values. To avoid
this, just tap the Reset button on the Main Panel to create the new format,
and re-define your preferences. From Version 2.4, if the new version is
detected a reset is triggered automatically. If there is still a problem with
strange parameter values and related errors, just reset, and please let me
know.

     http://www.geocities.com/retro_01775/ptbody.htm


PLATFORM:

The Morse Pilot application has been deployed on PalmPilot Professional with
III upgrade (PalmOS 3.0), Palm IIIc (PalmOS 3.5), and Vx (PalmOS 3.5), and
I have received reports that it runs on the mXXX series. I do not know if
Morse Pilot runs on hi res devices.  Note that the timing of the realtime
I/O functions is not optimal when run on POSE/POSER (PalmOS emulator).

There is no PocketPC, WinCE etc. version of Morse Pilot.


KNOWN ISSUES:

1. Morse Pilot does not work if any of the libraries are not installed. This
   is not a bug!

2. Morse Pilot does not work if the app or any of the libraries are on a
   HandEra memory card (thanks for this report, Brenda). It is likely that
   this also applies to other memory cards. This does not apply to flash ROM,
   though the preferences file must not be in flash ROM since it is regularly
   updated. This is not a bug either!

3. The display is not correctly detected by PalmOS 3.1 and PalmOS 3.3 devices.
   (thanks to Norm and Oliver for pointing this out).
   To handle such cases, a separate black and white version of Morse Pilot was
   included (from Version 2.5.3). This is not a Morse Pilot bug!
   From Morse Pilot 3.1 this version has been discontinued.

4. If you beam Morse Pilot to another handheld, the libraries and text files
   must also be beamed or the app will not work on the other handheld. Nor
   is this a Morse Pilot bug.

5. The Palm IIIc will not accept Graffiti or stylus taps properly if
   the screen contrast is set too high. This is not a MorsePilot bug.
   My guess is that the increased power consumption triggers a CPU slowdown.
   The workaround is to set the contrast slider to 50% or less.

6. Please mail bug reports, comments and suggestions to the author:
    <[e-mail]>
   Please post reviews at <www.palmgear.com> (search for Morse Pilot).


FYI:

Morse Pilot was developed completely (except for PRC compilation, which
used the PocketC Desktop Development Environment) with the following onboard
tools using graffiti input:

- PktC onboard compiler - I recommend PktC very highly as a development
  platform: see <www.orbworks.com>
- PToolboxLib PktC library for graphics and sound, also highly recommended:
  see <www.geocities.com/retro_01775/PToolboxLib.htm>
- peditPro (for efficient source code editing in memo format)
- iSilo (with format conversion on a Linux box, for making and consulting
  onboard manuals)
- RsrcEdit (for PDB verification and modification)
- BitmapBuddy, BitStudio (PktC applets for PktC format bitmap creation),
- Hackmaster 0.91 (recently, X-Master) and
   - EasyLaunch hack (for very quick switching between apps)
   - FindHack (for global search of source code)
   - Afterburner (overclocker for fast compilation)
   - QuickBits (for faster graphics)
- FlashPro for using ROM space
- PCCompress, an onboard zipper, for creating extra memory space
- The freeware Eudora Palm Internet Suite with a Siemens GSM mobile phone,
  for quick consultation with you and other developers

If you use speedup software, you do this entirely at your own risk; back up
all your software before trying it.


CREDITS:

The main credits go to Jeremy Dewey (for PocketC), Rick Huebner (for MathLib),
Joseph H. Stadolnik III (for PToolboxLib for PocketC), and Les Johnstone
(for the QSO texts).

Some of the "pioneer" users in the black and white Version 1.n days are
specifically thanked on the about panel (tap menu button). Of these Gilles
deserves mention for requesting colour, and external databases rather than
memos. Thanks also to Steve and Rainer for suggestions about custom lesson
memos, to Doug for making me aware that Morse Pilot works with an external
keyboard. More recently, thanks to Oliver for patiently testing the BW version
for PalmOS 3.n, n<5, since I don't have the ROMs for the problem devices,
and Hansj÷rg for suggesting an extension of logging to custom memo lessons.

And thanks to all those who just expressed appreciation, especially to Doug
for a very kind and unexpected gesture :)

Finally, apologies to Garrick and Wayne, whose interesting suggestion I have
not been able to include, namely to interface the handheld with a mobile QRP Tx
and Rx. This would require the construction of a small I/O box. Maybe the
simplest strategy for output (and the safest one wrt the hardware) would be
to use a small mike unit attached to the back of the handheld, with a pulse
former and switch. Input would require a very clean signal, and would have to
go via the IR or serial interfaces - unless someone really wants to build a
robot finger to tap on the screen... I haven't done any hardware designing for
ages, so any offers to design this box?

If you want to post a review on PalmGear, go to <www.palmgear.com>, and search
for "Morse Pilot".


RELEASE NOTES

VERSION 3.1
- Morse Pilot 3.1 is a technical release which was built because a new PocketC
  compiler version is available. The functionality of Morse Pilot has not
  changed.
- As from Morse Pilot 3.1 the PocketC runtime app version has been discontinued,
  thus simplifying the distribution. The runtime app version is ONLY useful
  if you have very low memory AND are running other PocketC runtime
  applications. If this applies to you, let me know.
- Some older versions of PalmOS have incompatible grey-scale graphics. If you
  have this problem, let me know.

VERSION 3.0
- Morse Pilot has undergone so many metamorphoses since Version since 2.0
  that it was time to define a new major release
- Library installation and version checks are now carried out when the
  app is launched, and warnings to install them are triggered if the version
  numbers are less than those of the distributed version
- MEMO LOG format slightly modified
- MEMO LOG switch also in Calibrate & Set Audio panels
- Fixed MEMO LOG length test bug
- Some alert messages shortened

VERSION 2.6.2
- Fixed bug which blocked memo text output (result of memo logging extension)

VERSION 2.6.1
- Extended memo logging function to custom memo lessons

VERSION 2.6
- Included line input timeout selection in Calibrate and HELP+UI panels
- Modified HELP+UI menu button ordering and text
- Modified grey scale values
- Extended range of Farnsworth factor to 1...20
- Fixed second call of menu-button about panel
- Fixed text overwriting and flash colours in BW edition
- Revised button handling code
- Modified flash output function logic and appearance

VERSION 2.5.5
- Interim version with changed BW version
- Set minimum 3 WPM

VERSION 2.5.4
- Changed "Generator" to "Output" in panel buttons
- Fixed display bug when input box is terminated with empty line
- Extended range of Farnsworth factor to 1...15
- Added Farnsworth factor reset on WPM change
- Modified installation guidelines in README.txt

VERSIONS 2.5, 2.5.1, 2.5.2, 2.5.3
- Modified bw/greyscale/colour display detection
- Fixed initialisation of lessons in OUTPUT panel
- Fixed TEST histogram
- Fixed misleading histogram reset warning
- Included black and white version in distribution for PalmOS 3.1 / 3.3 users
  (from 2.5.3)
- Changed use of graphics buffering:
    * now 3 levels of CopyBuf instead of saveg()/restoreg() stack
    * now re-drawing instead of graphics buffer at main panel level
- Fixed memo custom lesson issue
- Modified lesson termination logic
- Slightly modified histogram caption

VERSION 2.4
- Progress monitoring histogram for OUTPUT Lessons function in TEST mode
- Option for additional custom lessons loaded from MemoPad
- Visual morse flashing option (most suitable for units with bright TFT screen,
  such as Palm IIIc), for deaf users and acoustically hostile environments
- On/Off switch for hard button functions
- Minor modification of tutor messages
- Minor rearrangement and re-naming of menu items (earcon, memo hard button
  switches now under Help - UI)
- Memo text log function extended to INPUT

VERSION 2.3.1
- Correction of menu logic for Help/DXCC selection

VERSION 2.3
- Volume control levels under Sound ON in Set Audio panel
- OUTPUT text log memo for checking written results
- Improved alert and confirm button behaviour
- Fourth freely definable text register added

VERSION 2.2.1
- Bugfixes for HELP:General UI issue and MorseQSOdoc.pdb format issue
- Addition of spelling alphabet to random character morse output function

VERSION 2.2
- Reorganisation of distribution
- Improvement of initialisation and exit handling
- Tone feedback option for Morse decoder
- DXCC database search (^ operator marks beginning of search string if needed)

VERSION 2.1
- hard button navigation
- Earcon SUI (Sound User Interface) for blind users
- Database with 200 QSO texts by Les Johnstone, GM0SOZ, accessed by
  - random selection
  - selection by number
- Elbug simulator
- Improvement of support for Farnsworth method timing
- Additional widgets for GUI feedback
- Pen select to line input widget
- Slight re-arrangement and re-naming of buttons in GUI panels
- Addition of help information
- Format of preferences db changed to reduce size and access time
  Note: Some preferences will have to be re-entered in Morse Pilot 2.1

VERSION 2.0
- New colour, greyscale or b/w GUI (hardware dependent)
- Additional calibration parameters and greater calibration precision
- New output functions with tutor mode option
- MathLib is now required

VERSION 1.2
- GUI: the PToolboxLib library is now required
- Calibrator Module: sound quality check added, other minor improvements
- MathLib is not required, but if installed, slightly more statistical
  information is provided for calibrateion

VERSION 1.1
- First distributed version, basic b/w functionality